Create OC Essential Service from Lead with IP Group

This request enables you to create a new service from lead with an IP Group used to create a SIP connection between the customer tenant service and the Online PSTN gateway. Two new IP Groups are created on the SBC device that is configured to connect calls between the PSTN trunk and Microsoft Teams, one for the SIP leg (<IP_Group_Name-c) and another for the Teams leg (<IP_Group_Name-t). On Live Platform , a single IP Group representing the SIP leg is created serving as the SIP Connection between the customer tenant service and the Online PSTN gateway.

IP Groups are mandatory for SIP Registration.

By default, Operator Connect is configured to work with Microsoft Operator Connect 'peering' mode with two IP groups, one for the Microsoft Teams connection and the other for the SIP Trunk connection. The default Operator Connect Onboarding script creates a default Proxy Set 'Teams-OC ' and default IP Group 'Teams-OC' for this purpose (see OC Essential default SBC Onboarding script).

Using this request, two new IP Groups are created on the SBC device for the service, one for the SIP leg (<IP_Group_Name-c) and another for the Teams leg (<IP_Group_Name-t). On the Live Platform portal, a single IP Group is created serving as the SIP Connection between the customer tenant service and the Online PSTN gateway.

URI

Copy 
{{baseUrl}}/api/v3/customer

HTTP Method

POST

Request Body

Parameter

Type

Description

ConfigurationName

string
■ OcEssential_IPGROUP_TYPE

CustomerShortName

string

Customer short name with the following validation rules:

■ Length between 3 and 15 characters
■ No spaces
■ Include only literal and numerical characters and underscores

CustomerFulName

string

Generally the company name, however, any value can be used.

siteLocation
■ siteLocationName: string
■ sbcId: integer
■ sbcOnboardingScript: integer
■ sbcCleanupScript: integer
■ sbcOcUploadNumberScript: integer
■ sbcOcReleaseNumberScript: integer

The configured SBC used to manage calls for this site location.

siteLocationName

string

The name of the primary SIP connection for this service.

sbcId

integer

The SBC Id in the SBC List in the Live Platform database (see Get SBC Devices).

sbcOnboardingScript

integer

The SBC Onboarding script number in the Live Platform database (see Get Script Templates).

sbcCleanupScript

integer

The matching script number in the Live Platform database for Cleanup of the Onboarding script (see Get Script Templates).

sbcOcUploadNumberScript

integer

The script number in the Live Platform database for uploading numbers to the Operator Connect service (see Get Script Templates).

sbcOcReleaseNumberScript

integer

The matching script number in the Live Platform database to release numbers from the Operator Connect service (see Get Script Templates).

ovocCustomerType

One of the following values:

■ IPGROUP_TYPE string
■ TENANT_TYPE string
■ IP Group: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required).
■ Tenant ID:-The new customer is created based on the Tenant's Azure ID

channelId

string

Id of the channel to attach to the service.

lcCustomerId

string

The Id of the Customer entity in the Operation Center portal. When you specify this value, the new service is created under this entity in the Live Platform topology tree.

This value is currently not retrievable using the REST API. If not specified, both a new customer and service entity are created as separate entities in the Operation Center portal with the same shortName as shown in the example figures below.

Workaround: As a temporary workaround for retrieving this value:

1. Select the relevant customer entity in the Operation Center portal.
2. Open the F12 Debugging mode, select the tabs as shown in the figure below.
3. Copy the 'id' value for the relevant customer.

If you cannot find the relevant value for your customer verify that the number of entries displayed includes your customer. If not, change the page filters to display more entries

msTenantId

string

Microsoft subscription Tenant ID of the Customer lead.

leadId

string

The Id generated for the lead (see Get All OC Leads).

invitationEmail

string

Email of the customer tenant Global Admin or Service account operator used for Onboarding and securing the connection to the customer M365 platform.

licenseType

integer

OC Essential: 3

licensedUsersCount

integer

The number of user licenses to allocate for the service.

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant when Live Platform OC license is applied.

■ If this field has a value: The Guid of customer created by the Live Platform for the OC lead with the given msTenantid. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).
■ If this field is null: An OC license has not yet been applied to the customer lead.

teamsQos
■ applicationID string
■ applicationPassword string

Credentials of the Application Registration on the customer tenant to connect to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users. This registration must be added to the customer tenant (see Managing Teams Devices).

applicationID

string

The Application (Client) Id of the Application Registration for connecting to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

applicationPassword

string

The Client Secret of the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■ CustomVar.Variable1: <: IPPBX-ProxyAddress>
■ CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>
■ CustomVar.Variable3: <SIP-HostName>

 

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

additionalProp1

string

Custom Script variable argument. For example IP-Network.

additionalProp2

string

Custom Script argument. For example, IP-SubnetBits.

additionalProp3

string

Custom Script argument. For example, Trusted-IP-Network.

webhooks
■ invitationIsPending string
■ customerCreated string
■ didChange string

Webhooks push notification details (see Trigger Notification Email for New Leads).

The API requests for this feature are currently not supported.

invitationIsPending

string

Indicates that the Customer Invitation is pending for completion of the Invitation wizard process to secure connection with the customer M365 platform either through Delegated Token or Application Registration connection.

customerCreated

string

Indicates that the connection to the customer platform has been successfully secured and the service has been successfully created.

didChange

string

Indicates that a number has been uploaded or released for a service.

CallingProfileConfigurationTemplateId

integer

The Id of the Calling Profile Template.

This value can currently only be retrieved from the Web interface.

Example Request Body

Copy 

{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "f9f53ee0-56e1-43f6-8fe3-5fb322986657",
  "customerShortName": "Bradx35340067",
  "customerFullName": "Bradx35340067",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}

Example Response

The initial response displays the Task Id.

Parameter

 

Type

Description

Task Id

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wst string in the prefix is unique for this endpoint.
Copy 
{
"jobId": "wst_80b54f45-6643-4fdf-960a-638c18edb787"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy 
{
    "id": "wst_80b54f45-6643-4fdf-960a-638c18edb787",
    "status": "CompletedSuccess",
    "details": [
        "Converted"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "SBC sbc-onboarding done for site Bradx35340067."
        },
        {
            "level": "Information",
            "message": "Site created in Ovoc"
        }
    ],
    "outputData": {}
}

Response Codes

■ 200 Success

Parameter

Type

Description

id

string

Task Id

status

string

One of the following values:

■ In Progress
■ Completed Success
■ Completed Failed

details

string

One of the following values:

■ Converted

executionMessages

list array

List array including the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string
■ The following messages are displayed if the customer is created successfully (displayed in the output of the Get Task Id request):
Copy 
 "message": "Site created in Ovoc"
Copy 
"message": "SBC sbc-onboarding done for site Bradx35340067."
■ The following Request body includes a customer name with more than 15 characters.
Copy 
{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "7463427b-8c95-45b4-90ec-7710da369c32",
  "customerShortName": "BradEurope4497123456",
  "customerFullName": "BradEurope44972123456",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}
✔ As a result, the following error is displayed in the output of the Get Task Id request):
Copy 
{
    "id": "wst_df298001-41b3-495a-804b-aebecb028723",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "'Customer Short Name' must be between 3 and 15 characters."
        }
    ],
    "outputData": {}
}
■ The following Request body includes an invalid character ".":
Copy 
 {
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "msTenantId": "7463427b-8c95-45b4-90ec-7710da369c32",
  "customerShortName": "BradEurope.4497",
  "customerFullName": "BradEurope4497",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}

}
✔ As a result, the following error is displayed in the output of the Get Task Id request:
Copy 
{
    "id": "wst_7accb116-e200-4008-b97d-345cea3250df",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Customer Short Name contains invalid characters. Allowed characters: letters, numbers and '_'."
        },
        {
            "level": "Error",
            "message": "Customer Full Name contains invalid characters. Allowed characters: letters, numbers, _, ' and space."
        }
    ],
    "outputData": {}
}

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).

If this field is null: An OC license has not yet been applied to the customer lead.

outputData

list array

Additional information.
■ 405 Method Not Allowed:
Copy 
{
    "type": "https://httpstatuses.com/500",
    "title": "Internal Server Error",
    "status": 500,
    "traceId": "00-5bcfb1f75627574e43998a4558b34f5e-85a4aabfabc87feb-00"
}
■ 500 Internal Server Error
Copy 
{
    "type": "https://httpstatuses.com/500",
    "title": "Internal Server Error",
    "status": 500,
    "traceId": "00-5bcfb1f75627574e43998a4558b34f5e-85a4aabfabc87feb-00"
}